<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Advanced Usage &mdash; Requests 2.3.0 documentation</title>
    
    <link rel="stylesheet" href="../_static/flasky.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../',
        VERSION:     '2.3.0',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <link rel="top" title="Requests 2.3.0 documentation" href="../index.html" />
    <link rel="next" title="Authentication" href="authentication.html" />
    <link rel="prev" title="Quickstart" href="quickstart.html" />
   
  
  <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9">
  <script type="text/javascript" src="https://gumroad.com/js/gumroad.js"></script>

  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="../py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="authentication.html" title="Authentication"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="quickstart.html" title="Quickstart"
             accesskey="P">previous</a> |</li>
        <li><a href="../index.html">Requests 2.3.0 documentation</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="advanced-usage">
<span id="advanced"></span><h1>Advanced Usage<a class="headerlink" href="#advanced-usage" title="Permalink to this headline">¶</a></h1>
<p>This document covers some of Requests more advanced features.</p>
<div class="section" id="session-objects">
<h2>Session Objects<a class="headerlink" href="#session-objects" title="Permalink to this headline">¶</a></h2>
<p>The Session object allows you to persist certain parameters across
requests. It also persists cookies across all requests made from the
Session instance.</p>
<p>A Session object has all the methods of the main Requests API.</p>
<p>Let&#8217;s persist some cookies across requests:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">s</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">Session</span><span class="p">()</span>

<span class="n">s</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">&#39;http://httpbin.org/cookies/set/sessioncookie/123456789&#39;</span><span class="p">)</span>
<span class="n">r</span> <span class="o">=</span> <span class="n">s</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">&quot;http://httpbin.org/cookies&quot;</span><span class="p">)</span>

<span class="k">print</span><span class="p">(</span><span class="n">r</span><span class="o">.</span><span class="n">text</span><span class="p">)</span>
<span class="c"># &#39;{&quot;cookies&quot;: {&quot;sessioncookie&quot;: &quot;123456789&quot;}}&#39;</span>
</pre></div>
</div>
<p>Sessions can also be used to provide default data to the request methods. This
is done by providing data to the properties on a Session object:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">s</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">Session</span><span class="p">()</span>
<span class="n">s</span><span class="o">.</span><span class="n">auth</span> <span class="o">=</span> <span class="p">(</span><span class="s">&#39;user&#39;</span><span class="p">,</span> <span class="s">&#39;pass&#39;</span><span class="p">)</span>
<span class="n">s</span><span class="o">.</span><span class="n">headers</span><span class="o">.</span><span class="n">update</span><span class="p">({</span><span class="s">&#39;x-test&#39;</span><span class="p">:</span> <span class="s">&#39;true&#39;</span><span class="p">})</span>

<span class="c"># both &#39;x-test&#39; and &#39;x-test2&#39; are sent</span>
<span class="n">s</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">&#39;http://httpbin.org/headers&#39;</span><span class="p">,</span> <span class="n">headers</span><span class="o">=</span><span class="p">{</span><span class="s">&#39;x-test2&#39;</span><span class="p">:</span> <span class="s">&#39;true&#39;</span><span class="p">})</span>
</pre></div>
</div>
<p>Any dictionaries that you pass to a request method will be merged with the
session-level values that are set. The method-level parameters override session
parameters.</p>
<div class="admonition-remove-a-value-from-a-dict-parameter admonition">
<p class="first admonition-title">Remove a Value From a Dict Parameter</p>
<p class="last">Sometimes you&#8217;ll want to omit session-level keys from a dict parameter. To
do this, you simply set that key&#8217;s value to <tt class="docutils literal"><span class="pre">None</span></tt> in the method-level
parameter. It will automatically be omitted.</p>
</div>
<p>All values that are contained within a session are directly available to you.
See the <a class="reference internal" href="../api.html#sessionapi"><em>Session API Docs</em></a> to learn more.</p>
</div>
<div class="section" id="request-and-response-objects">
<h2>Request and Response Objects<a class="headerlink" href="#request-and-response-objects" title="Permalink to this headline">¶</a></h2>
<p>Whenever a call is made to <tt class="docutils literal"><span class="pre">requests.get()</span></tt> and friends you are doing two
major things. First, you are constructing a <tt class="docutils literal"><span class="pre">Request</span></tt> object which will be
sent off to a server to request or query some resource. Second, a <tt class="docutils literal"><span class="pre">Response</span></tt>
object is generated once <tt class="docutils literal"><span class="pre">requests</span></tt> gets a response back from the server.
The Response object contains all of the information returned by the server and
also contains the <tt class="docutils literal"><span class="pre">Request</span></tt> object you created originally. Here is a simple
request to get some very important information from Wikipedia&#8217;s servers:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">&#39;http://en.wikipedia.org/wiki/Monty_Python&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>If we want to access the headers the server sent back to us, we do this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">headers</span>
<span class="go">{&#39;content-length&#39;: &#39;56170&#39;, &#39;x-content-type-options&#39;: &#39;nosniff&#39;, &#39;x-cache&#39;:</span>
<span class="go">&#39;HIT from cp1006.eqiad.wmnet, MISS from cp1010.eqiad.wmnet&#39;, &#39;content-encoding&#39;:</span>
<span class="go">&#39;gzip&#39;, &#39;age&#39;: &#39;3080&#39;, &#39;content-language&#39;: &#39;en&#39;, &#39;vary&#39;: &#39;Accept-Encoding,Cookie&#39;,</span>
<span class="go">&#39;server&#39;: &#39;Apache&#39;, &#39;last-modified&#39;: &#39;Wed, 13 Jun 2012 01:33:50 GMT&#39;,</span>
<span class="go">&#39;connection&#39;: &#39;close&#39;, &#39;cache-control&#39;: &#39;private, s-maxage=0, max-age=0,</span>
<span class="go">must-revalidate&#39;, &#39;date&#39;: &#39;Thu, 14 Jun 2012 12:59:39 GMT&#39;, &#39;content-type&#39;:</span>
<span class="go">&#39;text/html; charset=UTF-8&#39;, &#39;x-cache-lookup&#39;: &#39;HIT from cp1006.eqiad.wmnet:3128,</span>
<span class="go">MISS from cp1010.eqiad.wmnet:80&#39;}</span>
</pre></div>
</div>
<p>However, if we want to get the headers we sent the server, we simply access the
request, and then the request&#8217;s headers:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">request</span><span class="o">.</span><span class="n">headers</span>
<span class="go">{&#39;Accept-Encoding&#39;: &#39;identity, deflate, compress, gzip&#39;,</span>
<span class="go">&#39;Accept&#39;: &#39;*/*&#39;, &#39;User-Agent&#39;: &#39;python-requests/1.2.0&#39;}</span>
</pre></div>
</div>
</div>
<div class="section" id="prepared-requests">
<h2>Prepared Requests<a class="headerlink" href="#prepared-requests" title="Permalink to this headline">¶</a></h2>
<p>Whenever you receive a <a class="reference internal" href="../api.html#requests.Response" title="requests.Response"><tt class="xref py py-class docutils literal"><span class="pre">Response</span></tt></a> object
from an API call or a Session call, the <tt class="docutils literal"><span class="pre">request</span></tt> attribute is actually the
<tt class="docutils literal"><span class="pre">PreparedRequest</span></tt> that was used. In some cases you may wish to do some extra
work to the body or headers (or anything else really) before sending a
request. The simple recipe for this is the following:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">requests</span> <span class="kn">import</span> <span class="n">Request</span><span class="p">,</span> <span class="n">Session</span>

<span class="n">s</span> <span class="o">=</span> <span class="n">Session</span><span class="p">()</span>
<span class="n">req</span> <span class="o">=</span> <span class="n">Request</span><span class="p">(</span><span class="s">&#39;GET&#39;</span><span class="p">,</span> <span class="n">url</span><span class="p">,</span>
    <span class="n">data</span><span class="o">=</span><span class="n">data</span><span class="p">,</span>
    <span class="n">headers</span><span class="o">=</span><span class="n">header</span>
<span class="p">)</span>
<span class="n">prepped</span> <span class="o">=</span> <span class="n">req</span><span class="o">.</span><span class="n">prepare</span><span class="p">()</span>

<span class="c"># do something with prepped.body</span>
<span class="c"># do something with prepped.headers</span>

<span class="n">resp</span> <span class="o">=</span> <span class="n">s</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="n">prepped</span><span class="p">,</span>
    <span class="n">stream</span><span class="o">=</span><span class="n">stream</span><span class="p">,</span>
    <span class="n">verify</span><span class="o">=</span><span class="n">verify</span><span class="p">,</span>
    <span class="n">proxies</span><span class="o">=</span><span class="n">proxies</span><span class="p">,</span>
    <span class="n">cert</span><span class="o">=</span><span class="n">cert</span><span class="p">,</span>
    <span class="n">timeout</span><span class="o">=</span><span class="n">timeout</span>
<span class="p">)</span>

<span class="k">print</span><span class="p">(</span><span class="n">resp</span><span class="o">.</span><span class="n">status_code</span><span class="p">)</span>
</pre></div>
</div>
<p>Since you are not doing anything special with the <tt class="docutils literal"><span class="pre">Request</span></tt> object, you
prepare it immediately and modify the <tt class="docutils literal"><span class="pre">PreparedRequest</span></tt> object. You then
send that with the other parameters you would have sent to <tt class="docutils literal"><span class="pre">requests.*</span></tt> or
<tt class="docutils literal"><span class="pre">Session.*</span></tt>.</p>
<p>However, the above code will lose some of the advantages of having a Requests
<a class="reference internal" href="../api.html#requests.Session" title="requests.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a> object. In particular,
<a class="reference internal" href="../api.html#requests.Session" title="requests.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a>-level state such as cookies will
not get applied to your request. To get a
<a class="reference internal" href="../api.html#requests.PreparedRequest" title="requests.PreparedRequest"><tt class="xref py py-class docutils literal"><span class="pre">PreparedRequest</span></tt></a> with that state
applied, replace the call to <a class="reference internal" href="../api.html#requests.Request.prepare" title="requests.Request.prepare"><tt class="xref py py-meth docutils literal"><span class="pre">Request.prepare()</span></tt></a> with a call to
<a class="reference internal" href="../api.html#requests.Session.prepare_request" title="requests.Session.prepare_request"><tt class="xref py py-meth docutils literal"><span class="pre">Session.prepare_request()</span></tt></a>, like this:</p>
<div class="highlight-python"><div class="highlight"><pre>from requests import Request, Session

s = Session()
req = Request(&#39;GET&#39;,  url,
    data=data
    headers=headers
)

prepped = s.prepare_request(req)

# do something with prepped.body
# do something with prepped.headers

resp = s.send(prepped,
    stream=stream,
    verify=verify,
    proxies=proxies,
    cert=cert,
    timeout=timeout
)

print(resp.status_code)
</pre></div>
</div>
</div>
<div class="section" id="ssl-cert-verification">
<span id="verification"></span><h2>SSL Cert Verification<a class="headerlink" href="#ssl-cert-verification" title="Permalink to this headline">¶</a></h2>
<p>Requests can verify SSL certificates for HTTPS requests, just like a web browser.
To check a host&#8217;s SSL certificate, you can use the <tt class="docutils literal"><span class="pre">verify</span></tt> argument:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">&#39;https://kennethreitz.com&#39;</span><span class="p">,</span> <span class="n">verify</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="go">requests.exceptions.SSLError: hostname &#39;kennethreitz.com&#39; doesn&#39;t match either of &#39;*.herokuapp.com&#39;, &#39;herokuapp.com&#39;</span>
</pre></div>
</div>
<p>I don&#8217;t have SSL setup on this domain, so it fails. Excellent. GitHub does though:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">&#39;https://github.com&#39;</span><span class="p">,</span> <span class="n">verify</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="go">&lt;Response [200]&gt;</span>
</pre></div>
</div>
<p>You can also pass <tt class="docutils literal"><span class="pre">verify</span></tt> the path to a CA_BUNDLE file for private certs. You can also set the <tt class="docutils literal"><span class="pre">REQUESTS_CA_BUNDLE</span></tt> environment variable.</p>
<p>Requests can also ignore verifying the SSL certificate if you set <tt class="docutils literal"><span class="pre">verify</span></tt> to False.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">&#39;https://kennethreitz.com&#39;</span><span class="p">,</span> <span class="n">verify</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
<span class="go">&lt;Response [200]&gt;</span>
</pre></div>
</div>
<p>By default, <tt class="docutils literal"><span class="pre">verify</span></tt> is set to True. Option <tt class="docutils literal"><span class="pre">verify</span></tt> only applies to host certs.</p>
<p>You can also specify a local cert to use as client side certificate, as a single
file (containing the private key and the certificate) or as a tuple of both
file&#8217;s path:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">&#39;https://kennethreitz.com&#39;</span><span class="p">,</span> <span class="n">cert</span><span class="o">=</span><span class="p">(</span><span class="s">&#39;/path/server.crt&#39;</span><span class="p">,</span> <span class="s">&#39;/path/key&#39;</span><span class="p">))</span>
<span class="go">&lt;Response [200]&gt;</span>
</pre></div>
</div>
<p>If you specify a wrong path or an invalid cert:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">&#39;https://kennethreitz.com&#39;</span><span class="p">,</span> <span class="n">cert</span><span class="o">=</span><span class="s">&#39;/wrong_path/server.pem&#39;</span><span class="p">)</span>
<span class="go">SSLError: [Errno 336265225] _ssl.c:347: error:140B0009:SSL routines:SSL_CTX_use_PrivateKey_file:PEM lib</span>
</pre></div>
</div>
</div>
<div class="section" id="body-content-workflow">
<h2>Body Content Workflow<a class="headerlink" href="#body-content-workflow" title="Permalink to this headline">¶</a></h2>
<p>By default, when you make a request, the body of the response is downloaded
immediately. You can override this behaviour and defer downloading the response
body until you access the <a class="reference internal" href="../api.html#requests.Response.content" title="requests.Response.content"><tt class="xref py py-class docutils literal"><span class="pre">Response.content</span></tt></a>
attribute with the <tt class="docutils literal"><span class="pre">stream</span></tt> parameter:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">tarball_url</span> <span class="o">=</span> <span class="s">&#39;https://github.com/kennethreitz/requests/tarball/master&#39;</span>
<span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">tarball_url</span><span class="p">,</span> <span class="n">stream</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
</pre></div>
</div>
<p>At this point only the response headers have been downloaded and the connection
remains open, hence allowing us to make content retrieval conditional:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">if</span> <span class="nb">int</span><span class="p">(</span><span class="n">r</span><span class="o">.</span><span class="n">headers</span><span class="p">[</span><span class="s">&#39;content-length&#39;</span><span class="p">])</span> <span class="o">&lt;</span> <span class="n">TOO_LONG</span><span class="p">:</span>
  <span class="n">content</span> <span class="o">=</span> <span class="n">r</span><span class="o">.</span><span class="n">content</span>
  <span class="o">...</span>
</pre></div>
</div>
<p>You can further control the workflow by use of the <a class="reference internal" href="../api.html#requests.Response.iter_content" title="requests.Response.iter_content"><tt class="xref py py-class docutils literal"><span class="pre">Response.iter_content</span></tt></a>
and <a class="reference internal" href="../api.html#requests.Response.iter_lines" title="requests.Response.iter_lines"><tt class="xref py py-class docutils literal"><span class="pre">Response.iter_lines</span></tt></a> methods.
Alternatively, you can read the undecoded body from the underlying
urllib3 <a class="reference external" href="http://urllib3.readthedocs.org/en/latest/helpers.html#urllib3.response.HTTPResponse" title="(in urllib3 vdev)"><tt class="xref py py-class docutils literal"><span class="pre">urllib3.HTTPResponse</span></tt></a> at
<a class="reference internal" href="../api.html#requests.Response.raw" title="requests.Response.raw"><tt class="xref py py-class docutils literal"><span class="pre">Response.raw</span></tt></a>.</p>
<p>If you set <tt class="docutils literal"><span class="pre">stream</span></tt> to <tt class="docutils literal"><span class="pre">True</span></tt> when making a request, Requests cannot
release the connection back to the pool unless you consume all the data or call
<a class="reference internal" href="../api.html#requests.Response.close" title="requests.Response.close"><tt class="xref py py-class docutils literal"><span class="pre">Response.close</span></tt></a>. This can lead to
inefficiency with connections. If you find yourself partially reading request
bodies (or not reading them at all) while using <tt class="docutils literal"><span class="pre">stream=True</span></tt>, you should
consider using <tt class="docutils literal"><span class="pre">contextlib.closing</span></tt> (<a class="reference external" href="http://docs.python.org/2/library/contextlib.html#contextlib.closing">documented here</a>), like this:</p>
<div class="highlight-python"><div class="highlight"><pre>from contextlib import closing

with closing(requests.get(&#39;http://httpbin.org/get&#39;, stream=True)) as r:
    # Do things with the response here.
</pre></div>
</div>
</div>
<div class="section" id="keep-alive">
<h2>Keep-Alive<a class="headerlink" href="#keep-alive" title="Permalink to this headline">¶</a></h2>
<p>Excellent news —&nbsp;thanks to urllib3, keep-alive is 100% automatic within a session!
Any requests that you make within a session will automatically reuse the appropriate
connection!</p>
<p>Note that connections are only released back to the pool for reuse once all body
data has been read; be sure to either set <tt class="docutils literal"><span class="pre">stream</span></tt> to <tt class="docutils literal"><span class="pre">False</span></tt> or read the
<tt class="docutils literal"><span class="pre">content</span></tt> property of the <tt class="docutils literal"><span class="pre">Response</span></tt> object.</p>
</div>
<div class="section" id="streaming-uploads">
<h2>Streaming Uploads<a class="headerlink" href="#streaming-uploads" title="Permalink to this headline">¶</a></h2>
<p>Requests supports streaming uploads, which allow you to send large streams or
files without reading them into memory. To stream and upload, simply provide a
file-like object for your body:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s">&#39;massive-body&#39;</span><span class="p">,</span> <span class="s">&#39;rb&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
    <span class="n">requests</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s">&#39;http://some.url/streamed&#39;</span><span class="p">,</span> <span class="n">data</span><span class="o">=</span><span class="n">f</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="chunk-encoded-requests">
<h2>Chunk-Encoded Requests<a class="headerlink" href="#chunk-encoded-requests" title="Permalink to this headline">¶</a></h2>
<p>Requests also supports Chunked transfer encoding for outgoing and incoming requests.
To send a chunk-encoded request, simply provide a generator (or any iterator without
a length) for your body:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">gen</span><span class="p">():</span>
    <span class="k">yield</span> <span class="s">&#39;hi&#39;</span>
    <span class="k">yield</span> <span class="s">&#39;there&#39;</span>

<span class="n">requests</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s">&#39;http://some.url/chunked&#39;</span><span class="p">,</span> <span class="n">data</span><span class="o">=</span><span class="n">gen</span><span class="p">())</span>
</pre></div>
</div>
</div>
<div class="section" id="post-multiple-multipart-encoded-files">
<h2>POST Multiple Multipart-Encoded Files<a class="headerlink" href="#post-multiple-multipart-encoded-files" title="Permalink to this headline">¶</a></h2>
<p>You can send multiple files in one request. For example, suppose you want to
upload image files to an HTML form with a multiple file field &#8216;images&#8217;:</p>
<blockquote>
<div>&lt;input type=&#8221;file&#8221; name=&#8221;images&#8221; multiple=&#8221;true&#8221; required=&#8221;true&#8221;/&gt;</div></blockquote>
<p>To do that, just set files to a list of tuples of (form_field_name, file_info):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">url</span> <span class="o">=</span> <span class="s">&#39;http://httpbin.org/post&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">multiple_files</span> <span class="o">=</span> <span class="p">[(</span><span class="s">&#39;images&#39;</span><span class="p">,</span> <span class="p">(</span><span class="s">&#39;foo.png&#39;</span><span class="p">,</span> <span class="nb">open</span><span class="p">(</span><span class="s">&#39;foo.png&#39;</span><span class="p">,</span> <span class="s">&#39;rb&#39;</span><span class="p">),</span> <span class="s">&#39;image/png&#39;</span><span class="p">)),</span>
<span class="go">                      (&#39;images&#39;, (&#39;bar.png&#39;, open(&#39;bar.png&#39;, &#39;rb&#39;), &#39;image/png&#39;))]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="n">url</span><span class="p">,</span> <span class="n">files</span><span class="o">=</span><span class="n">multiple_files</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">text</span>
<span class="go">{</span>
<span class="go">  ...</span>
<span class="go">  &#39;files&#39;: {&#39;images&#39;: &#39; ....&#39;}</span>
<span class="go">  &#39;Content-Type&#39;: &#39;multipart/form-data; boundary=3131623adb2043caaeb5538cc7aa0b3a&#39;,</span>
<span class="go">  ...</span>
<span class="go">}</span>
</pre></div>
</div>
</div>
<div class="section" id="event-hooks">
<h2>Event Hooks<a class="headerlink" href="#event-hooks" title="Permalink to this headline">¶</a></h2>
<p>Requests has a hook system that you can use to manipulate portions of
the request process, or signal event handling.</p>
<p>Available hooks:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">response</span></tt>:</dt>
<dd>The response generated from a Request.</dd>
</dl>
<p>You can assign a hook function on a per-request basis by passing a
<tt class="docutils literal"><span class="pre">{hook_name:</span> <span class="pre">callback_function}</span></tt> dictionary to the <tt class="docutils literal"><span class="pre">hooks</span></tt> request
parameter:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">hooks</span><span class="o">=</span><span class="nb">dict</span><span class="p">(</span><span class="n">response</span><span class="o">=</span><span class="n">print_url</span><span class="p">)</span>
</pre></div>
</div>
<p>That <tt class="docutils literal"><span class="pre">callback_function</span></tt> will receive a chunk of data as its first
argument.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">print_url</span><span class="p">(</span><span class="n">r</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
    <span class="k">print</span><span class="p">(</span><span class="n">r</span><span class="o">.</span><span class="n">url</span><span class="p">)</span>
</pre></div>
</div>
<p>If an error occurs while executing your callback, a warning is given.</p>
<p>If the callback function returns a value, it is assumed that it is to
replace the data that was passed in. If the function doesn&#8217;t return
anything, nothing else is effected.</p>
<p>Let&#8217;s print some request method arguments at runtime:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">&#39;http://httpbin.org&#39;</span><span class="p">,</span> <span class="n">hooks</span><span class="o">=</span><span class="nb">dict</span><span class="p">(</span><span class="n">response</span><span class="o">=</span><span class="n">print_url</span><span class="p">))</span>
<span class="go">http://httpbin.org</span>
<span class="go">&lt;Response [200]&gt;</span>
</pre></div>
</div>
</div>
<div class="section" id="custom-authentication">
<h2>Custom Authentication<a class="headerlink" href="#custom-authentication" title="Permalink to this headline">¶</a></h2>
<p>Requests allows you to use specify your own authentication mechanism.</p>
<p>Any callable which is passed as the <tt class="docutils literal"><span class="pre">auth</span></tt> argument to a request method will
have the opportunity to modify the request before it is dispatched.</p>
<p>Authentication implementations are subclasses of <tt class="docutils literal"><span class="pre">requests.auth.AuthBase</span></tt>,
and are easy to define. Requests provides two common authentication scheme
implementations in <tt class="docutils literal"><span class="pre">requests.auth</span></tt>: <tt class="docutils literal"><span class="pre">HTTPBasicAuth</span></tt> and <tt class="docutils literal"><span class="pre">HTTPDigestAuth</span></tt>.</p>
<p>Let&#8217;s pretend that we have a web service that will only respond if the
<tt class="docutils literal"><span class="pre">X-Pizza</span></tt> header is set to a password value. Unlikely, but just go with it.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">requests.auth</span> <span class="kn">import</span> <span class="n">AuthBase</span>

<span class="k">class</span> <span class="nc">PizzaAuth</span><span class="p">(</span><span class="n">AuthBase</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;Attaches HTTP Pizza Authentication to the given Request object.&quot;&quot;&quot;</span>
    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">username</span><span class="p">):</span>
        <span class="c"># setup any auth-related data here</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">username</span> <span class="o">=</span> <span class="n">username</span>

    <span class="k">def</span> <span class="nf">__call__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">r</span><span class="p">):</span>
        <span class="c"># modify and return the request</span>
        <span class="n">r</span><span class="o">.</span><span class="n">headers</span><span class="p">[</span><span class="s">&#39;X-Pizza&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">username</span>
        <span class="k">return</span> <span class="n">r</span>
</pre></div>
</div>
<p>Then, we can make a request using our Pizza Auth:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">&#39;http://pizzabin.org/admin&#39;</span><span class="p">,</span> <span class="n">auth</span><span class="o">=</span><span class="n">PizzaAuth</span><span class="p">(</span><span class="s">&#39;kenneth&#39;</span><span class="p">))</span>
<span class="go">&lt;Response [200]&gt;</span>
</pre></div>
</div>
</div>
<div class="section" id="streaming-requests">
<span id="id1"></span><h2>Streaming Requests<a class="headerlink" href="#streaming-requests" title="Permalink to this headline">¶</a></h2>
<p>With <a class="reference internal" href="../api.html#requests.Response.iter_lines" title="requests.Response.iter_lines"><tt class="xref py py-class docutils literal"><span class="pre">requests.Response.iter_lines()</span></tt></a> you can easily
iterate over streaming APIs such as the <a class="reference external" href="https://dev.twitter.com/docs/streaming-api">Twitter Streaming
API</a>. Simply
set <tt class="docutils literal"><span class="pre">stream</span></tt> to <tt class="docutils literal"><span class="pre">True</span></tt> and iterate over the response with
<a class="reference internal" href="../api.html#requests.Response.iter_lines" title="requests.Response.iter_lines"><tt class="xref py py-class docutils literal"><span class="pre">iter_lines()</span></tt></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">json</span>
<span class="kn">import</span> <span class="nn">requests</span>

<span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">&#39;http://httpbin.org/stream/20&#39;</span><span class="p">,</span> <span class="n">stream</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>

<span class="k">for</span> <span class="n">line</span> <span class="ow">in</span> <span class="n">r</span><span class="o">.</span><span class="n">iter_lines</span><span class="p">():</span>

    <span class="c"># filter out keep-alive new lines</span>
    <span class="k">if</span> <span class="n">line</span><span class="p">:</span>
        <span class="k">print</span><span class="p">(</span><span class="n">json</span><span class="o">.</span><span class="n">loads</span><span class="p">(</span><span class="n">line</span><span class="p">))</span>
</pre></div>
</div>
</div>
<div class="section" id="proxies">
<h2>Proxies<a class="headerlink" href="#proxies" title="Permalink to this headline">¶</a></h2>
<p>If you need to use a proxy, you can configure individual requests with the
<tt class="docutils literal"><span class="pre">proxies</span></tt> argument to any request method:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">requests</span>

<span class="n">proxies</span> <span class="o">=</span> <span class="p">{</span>
  <span class="s">&quot;http&quot;</span><span class="p">:</span> <span class="s">&quot;http://10.10.1.10:3128&quot;</span><span class="p">,</span>
  <span class="s">&quot;https&quot;</span><span class="p">:</span> <span class="s">&quot;http://10.10.1.10:1080&quot;</span><span class="p">,</span>
<span class="p">}</span>

<span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">&quot;http://example.org&quot;</span><span class="p">,</span> <span class="n">proxies</span><span class="o">=</span><span class="n">proxies</span><span class="p">)</span>
</pre></div>
</div>
<p>You can also configure proxies by setting the environment variables
<tt class="docutils literal"><span class="pre">HTTP_PROXY</span></tt> and <tt class="docutils literal"><span class="pre">HTTPS_PROXY</span></tt>.</p>
<div class="highlight-python"><div class="highlight"><pre>$ export HTTP_PROXY=&quot;http://10.10.1.10:3128&quot;
$ export HTTPS_PROXY=&quot;http://10.10.1.10:1080&quot;
$ python
&gt;&gt;&gt; import requests
&gt;&gt;&gt; requests.get(&quot;http://example.org&quot;)
</pre></div>
</div>
<p>To use HTTP Basic Auth with your proxy, use the <cite>http://user:password&#64;host/</cite> syntax:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">proxies</span> <span class="o">=</span> <span class="p">{</span>
    <span class="s">&quot;http&quot;</span><span class="p">:</span> <span class="s">&quot;http://user:pass@10.10.1.10:3128/&quot;</span><span class="p">,</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Note that proxy URLs must include the scheme.</p>
</div>
<div class="section" id="compliance">
<h2>Compliance<a class="headerlink" href="#compliance" title="Permalink to this headline">¶</a></h2>
<p>Requests is intended to be compliant with all relevant specifications and
RFCs where that compliance will not cause difficulties for users. This
attention to the specification can lead to some behaviour that may seem
unusual to those not familiar with the relevant specification.</p>
<div class="section" id="encodings">
<h3>Encodings<a class="headerlink" href="#encodings" title="Permalink to this headline">¶</a></h3>
<p>When you receive a response, Requests makes a guess at the encoding to
use for decoding the response when you access the <a class="reference internal" href="../api.html#requests.Response.text" title="requests.Response.text"><tt class="xref py py-attr docutils literal"><span class="pre">Response.text</span></tt></a> attribute. Requests will first check for an
encoding in the HTTP header, and if none is present, will use <a class="reference external" href="http://pypi.python.org/pypi/chardet">chardet</a> to attempt to guess the encoding.</p>
<p>The only time Requests will not do this is if no explicit charset
is present in the HTTP headers <strong>and</strong> the <tt class="docutils literal"><span class="pre">Content-Type</span></tt>
header contains <tt class="docutils literal"><span class="pre">text</span></tt>. In this situation, <a class="reference external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.7.1">RFC 2616</a> specifies
that the default charset must be <tt class="docutils literal"><span class="pre">ISO-8859-1</span></tt>. Requests follows the
specification in this case. If you require a different encoding, you can
manually set the <a class="reference internal" href="../api.html#requests.Response.encoding" title="requests.Response.encoding"><tt class="xref py py-attr docutils literal"><span class="pre">Response.encoding</span></tt></a>
property, or use the raw <a class="reference internal" href="../api.html#requests.Response.content" title="requests.Response.content"><tt class="xref py py-attr docutils literal"><span class="pre">Response.content</span></tt></a>.</p>
</div>
</div>
<div class="section" id="http-verbs">
<h2>HTTP Verbs<a class="headerlink" href="#http-verbs" title="Permalink to this headline">¶</a></h2>
<p>Requests provides access to almost the full range of HTTP verbs: GET, OPTIONS,
HEAD, POST, PUT, PATCH and DELETE. The following provides detailed examples of
using these various verbs in Requests, using the GitHub API.</p>
<p>We will begin with the verb most commonly used: GET. HTTP GET is an idempotent
method that returns a resource from a given URL. As a result, it is the verb
you ought to use when attempting to retrieve data from a web location. An
example usage would be attempting to get information about a specific commit
from GitHub. Suppose we wanted commit <tt class="docutils literal"><span class="pre">a050faf</span></tt> on Requests. We would get it
like so:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">requests</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">&#39;https://api.github.com/repos/kennethreitz/requests/git/commits/a050faf084662f3a352dd1a941f2c7c9f886d4ad&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>We should confirm that GitHub responded correctly. If it has, we want to work
out what type of content it is. Do this like so:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">if</span> <span class="n">r</span><span class="o">.</span><span class="n">status_code</span> <span class="o">==</span> <span class="n">requests</span><span class="o">.</span><span class="n">codes</span><span class="o">.</span><span class="n">ok</span><span class="p">:</span>
<span class="gp">... </span>    <span class="k">print</span><span class="p">(</span><span class="n">r</span><span class="o">.</span><span class="n">headers</span><span class="p">[</span><span class="s">&#39;content-type&#39;</span><span class="p">])</span>
<span class="gp">...</span>
<span class="go">application/json; charset=utf-8</span>
</pre></div>
</div>
<p>So, GitHub returns JSON. That&#8217;s great, we can use the <a class="reference internal" href="../api.html#requests.Response.json" title="requests.Response.json"><tt class="xref py py-meth docutils literal"><span class="pre">r.json</span></tt></a> method to parse it into Python objects.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">commit_data</span> <span class="o">=</span> <span class="n">r</span><span class="o">.</span><span class="n">json</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">commit_data</span><span class="o">.</span><span class="n">keys</span><span class="p">())</span>
<span class="go">[u&#39;committer&#39;, u&#39;author&#39;, u&#39;url&#39;, u&#39;tree&#39;, u&#39;sha&#39;, u&#39;parents&#39;, u&#39;message&#39;]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">commit_data</span><span class="p">[</span><span class="s">u&#39;committer&#39;</span><span class="p">])</span>
<span class="go">{u&#39;date&#39;: u&#39;2012-05-10T11:10:50-07:00&#39;, u&#39;email&#39;: u&#39;me@kennethreitz.com&#39;, u&#39;name&#39;: u&#39;Kenneth Reitz&#39;}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">commit_data</span><span class="p">[</span><span class="s">u&#39;message&#39;</span><span class="p">])</span>
<span class="go">makin&#39; history</span>
</pre></div>
</div>
<p>So far, so simple. Well, let&#8217;s investigate the GitHub API a little bit. Now,
we could look at the documentation, but we might have a little more fun if we
use Requests instead. We can take advantage of the Requests OPTIONS verb to
see what kinds of HTTP methods are supported on the url we just used.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">verbs</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">options</span><span class="p">(</span><span class="n">r</span><span class="o">.</span><span class="n">url</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">verbs</span><span class="o">.</span><span class="n">status_code</span>
<span class="go">500</span>
</pre></div>
</div>
<p>Uh, what? That&#8217;s unhelpful! Turns out GitHub, like many API providers, don&#8217;t
actually implement the OPTIONS method. This is an annoying oversight, but it&#8217;s
OK, we can just use the boring documentation. If GitHub had correctly
implemented OPTIONS, however, they should return the allowed methods in the
headers, e.g.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">verbs</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">options</span><span class="p">(</span><span class="s">&#39;http://a-good-website.com/api/cats&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">verbs</span><span class="o">.</span><span class="n">headers</span><span class="p">[</span><span class="s">&#39;allow&#39;</span><span class="p">])</span>
<span class="go">GET,HEAD,POST,OPTIONS</span>
</pre></div>
</div>
<p>Turning to the documentation, we see that the only other method allowed for
commits is POST, which creates a new commit. As we&#8217;re using the Requests repo,
we should probably avoid making ham-handed POSTS to it. Instead, let&#8217;s play
with the Issues feature of GitHub.</p>
<p>This documentation was added in response to Issue #482. Given that this issue
already exists, we will use it as an example. Let&#8217;s start by getting it.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">&#39;https://api.github.com/repos/kennethreitz/requests/issues/482&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">status_code</span>
<span class="go">200</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">issue</span> <span class="o">=</span> <span class="n">json</span><span class="o">.</span><span class="n">loads</span><span class="p">(</span><span class="n">r</span><span class="o">.</span><span class="n">text</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">issue</span><span class="p">[</span><span class="s">u&#39;title&#39;</span><span class="p">])</span>
<span class="go">Feature any http verb in docs</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">issue</span><span class="p">[</span><span class="s">u&#39;comments&#39;</span><span class="p">])</span>
<span class="go">3</span>
</pre></div>
</div>
<p>Cool, we have three comments. Let&#8217;s take a look at the last of them.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">r</span><span class="o">.</span><span class="n">url</span> <span class="o">+</span> <span class="s">u&#39;/comments&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">status_code</span>
<span class="go">200</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">comments</span> <span class="o">=</span> <span class="n">r</span><span class="o">.</span><span class="n">json</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">comments</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">keys</span><span class="p">())</span>
<span class="go">[u&#39;body&#39;, u&#39;url&#39;, u&#39;created_at&#39;, u&#39;updated_at&#39;, u&#39;user&#39;, u&#39;id&#39;]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">comments</span><span class="p">[</span><span class="mi">2</span><span class="p">][</span><span class="s">u&#39;body&#39;</span><span class="p">])</span>
<span class="go">Probably in the &quot;advanced&quot; section</span>
</pre></div>
</div>
<p>Well, that seems like a silly place. Let&#8217;s post a comment telling the poster
that he&#8217;s silly. Who is the poster, anyway?</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">comments</span><span class="p">[</span><span class="mi">2</span><span class="p">][</span><span class="s">u&#39;user&#39;</span><span class="p">][</span><span class="s">u&#39;login&#39;</span><span class="p">])</span>
<span class="go">kennethreitz</span>
</pre></div>
</div>
<p>OK, so let&#8217;s tell this Kenneth guy that we think this example should go in the
quickstart guide instead. According to the GitHub API doc, the way to do this
is to POST to the thread. Let&#8217;s do it.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">body</span> <span class="o">=</span> <span class="n">json</span><span class="o">.</span><span class="n">dumps</span><span class="p">({</span><span class="s">u&quot;body&quot;</span><span class="p">:</span> <span class="s">u&quot;Sounds great! I&#39;ll get right on it!&quot;</span><span class="p">})</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">url</span> <span class="o">=</span> <span class="s">u&quot;https://api.github.com/repos/kennethreitz/requests/issues/482/comments&quot;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="n">url</span><span class="o">=</span><span class="n">url</span><span class="p">,</span> <span class="n">data</span><span class="o">=</span><span class="n">body</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">status_code</span>
<span class="go">404</span>
</pre></div>
</div>
<p>Huh, that&#8217;s weird. We probably need to authenticate. That&#8217;ll be a pain, right?
Wrong. Requests makes it easy to use many forms of authentication, including
the very common Basic Auth.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">requests.auth</span> <span class="kn">import</span> <span class="n">HTTPBasicAuth</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">auth</span> <span class="o">=</span> <span class="n">HTTPBasicAuth</span><span class="p">(</span><span class="s">&#39;fake@example.com&#39;</span><span class="p">,</span> <span class="s">&#39;not_a_real_password&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="n">url</span><span class="o">=</span><span class="n">url</span><span class="p">,</span> <span class="n">data</span><span class="o">=</span><span class="n">body</span><span class="p">,</span> <span class="n">auth</span><span class="o">=</span><span class="n">auth</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">status_code</span>
<span class="go">201</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">content</span> <span class="o">=</span> <span class="n">r</span><span class="o">.</span><span class="n">json</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">content</span><span class="p">[</span><span class="s">u&#39;body&#39;</span><span class="p">])</span>
<span class="go">Sounds great! I&#39;ll get right on it.</span>
</pre></div>
</div>
<p>Brilliant. Oh, wait, no! I meant to add that it would take me a while, because
I had to go feed my cat. If only I could edit this comment! Happily, GitHub
allows us to use another HTTP verb, PATCH, to edit this comment. Let&#8217;s do
that.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">content</span><span class="p">[</span><span class="s">u&quot;id&quot;</span><span class="p">])</span>
<span class="go">5804413</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">body</span> <span class="o">=</span> <span class="n">json</span><span class="o">.</span><span class="n">dumps</span><span class="p">({</span><span class="s">u&quot;body&quot;</span><span class="p">:</span> <span class="s">u&quot;Sounds great! I&#39;ll get right on it once I feed my cat.&quot;</span><span class="p">})</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">url</span> <span class="o">=</span> <span class="s">u&quot;https://api.github.com/repos/kennethreitz/requests/issues/comments/5804413&quot;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">patch</span><span class="p">(</span><span class="n">url</span><span class="o">=</span><span class="n">url</span><span class="p">,</span> <span class="n">data</span><span class="o">=</span><span class="n">body</span><span class="p">,</span> <span class="n">auth</span><span class="o">=</span><span class="n">auth</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">status_code</span>
<span class="go">200</span>
</pre></div>
</div>
<p>Excellent. Now, just to torture this Kenneth guy, I&#8217;ve decided to let him
sweat and not tell him that I&#8217;m working on this. That means I want to delete
this comment. GitHub lets us delete comments using the incredibly aptly named
DELETE method. Let&#8217;s get rid of it.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">delete</span><span class="p">(</span><span class="n">url</span><span class="o">=</span><span class="n">url</span><span class="p">,</span> <span class="n">auth</span><span class="o">=</span><span class="n">auth</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">status_code</span>
<span class="go">204</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">headers</span><span class="p">[</span><span class="s">&#39;status&#39;</span><span class="p">]</span>
<span class="go">&#39;204 No Content&#39;</span>
</pre></div>
</div>
<p>Excellent. All gone. The last thing I want to know is how much of my ratelimit
I&#8217;ve used. Let&#8217;s find out. GitHub sends that information in the headers, so
rather than download the whole page I&#8217;ll send a HEAD request to get the
headers.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">head</span><span class="p">(</span><span class="n">url</span><span class="o">=</span><span class="n">url</span><span class="p">,</span> <span class="n">auth</span><span class="o">=</span><span class="n">auth</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">r</span><span class="o">.</span><span class="n">headers</span><span class="p">)</span>
<span class="gp">...</span>
<span class="go">&#39;x-ratelimit-remaining&#39;: &#39;4995&#39;</span>
<span class="go">&#39;x-ratelimit-limit&#39;: &#39;5000&#39;</span>
<span class="gp">...</span>
</pre></div>
</div>
<p>Excellent. Time to write a Python program that abuses the GitHub API in all
kinds of exciting ways, 4995 more times.</p>
</div>
<div class="section" id="link-headers">
<h2>Link Headers<a class="headerlink" href="#link-headers" title="Permalink to this headline">¶</a></h2>
<p>Many HTTP APIs feature Link headers. They make APIs more self describing and
discoverable.</p>
<p>GitHub uses these for <a class="reference external" href="http://developer.github.com/v3/#pagination">pagination</a>
in their API, for example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">url</span> <span class="o">=</span> <span class="s">&#39;https://api.github.com/users/kennethreitz/repos?page=1&amp;per_page=10&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">head</span><span class="p">(</span><span class="n">url</span><span class="o">=</span><span class="n">url</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">headers</span><span class="p">[</span><span class="s">&#39;link&#39;</span><span class="p">]</span>
<span class="go">&#39;&lt;https://api.github.com/users/kennethreitz/repos?page=2&amp;per_page=10&gt;; rel=&quot;next&quot;, &lt;https://api.github.com/users/kennethreitz/repos?page=6&amp;per_page=10&gt;; rel=&quot;last&quot;&#39;</span>
</pre></div>
</div>
<p>Requests will automatically parse these link headers and make them easily consumable:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">links</span><span class="p">[</span><span class="s">&quot;next&quot;</span><span class="p">]</span>
<span class="go">{&#39;url&#39;: &#39;https://api.github.com/users/kennethreitz/repos?page=2&amp;per_page=10&#39;, &#39;rel&#39;: &#39;next&#39;}</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">links</span><span class="p">[</span><span class="s">&quot;last&quot;</span><span class="p">]</span>
<span class="go">{&#39;url&#39;: &#39;https://api.github.com/users/kennethreitz/repos?page=7&amp;per_page=10&#39;, &#39;rel&#39;: &#39;last&#39;}</span>
</pre></div>
</div>
</div>
<div class="section" id="transport-adapters">
<h2>Transport Adapters<a class="headerlink" href="#transport-adapters" title="Permalink to this headline">¶</a></h2>
<p>As of v1.0.0, Requests has moved to a modular internal design. Part of the
reason this was done was to implement Transport Adapters, originally
<a class="reference external" href="http://www.kennethreitz.org/essays/the-future-of-python-http">described here</a>. Transport Adapters provide a mechanism to define interaction
methods for an HTTP service. In particular, they allow you to apply per-service
configuration.</p>
<p>Requests ships with a single Transport Adapter, the <a class="reference internal" href="../api.html#requests.adapters.HTTPAdapter" title="requests.adapters.HTTPAdapter"><tt class="xref py py-class docutils literal"><span class="pre">HTTPAdapter</span></tt></a>. This adapter provides the default Requests
interaction with HTTP and HTTPS using the powerful <a class="reference external" href="https://github.com/shazow/urllib3">urllib3</a> library. Whenever
a Requests <a class="reference internal" href="../api.html#requests.Session" title="requests.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a> is initialized, one of these is
attached to the <a class="reference internal" href="../api.html#requests.Session" title="requests.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a> object for HTTP, and one
for HTTPS.</p>
<p>Requests enables users to create and use their own Transport Adapters that
provide specific functionality. Once created, a Transport Adapter can be
mounted to a Session object, along with an indication of which web services
it should apply to.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">s</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">Session</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">s</span><span class="o">.</span><span class="n">mount</span><span class="p">(</span><span class="s">&#39;http://www.github.com&#39;</span><span class="p">,</span> <span class="n">MyAdapter</span><span class="p">())</span>
</pre></div>
</div>
<p>The mount call registers a specific instance of a Transport Adapter to a
prefix. Once mounted, any HTTP request made using that session whose URL starts
with the given prefix will use the given Transport Adapter.</p>
<p>Many of the details of implementing a Transport Adapter are beyond the scope of
this documentation, but take a look at the next example for a simple SSL use-
case. For more than that, you might look at subclassing
<tt class="docutils literal"><span class="pre">requests.adapters.BaseAdapter</span></tt>.</p>
<div class="section" id="example-specific-ssl-version">
<h3>Example: Specific SSL Version<a class="headerlink" href="#example-specific-ssl-version" title="Permalink to this headline">¶</a></h3>
<p>The Requests team has made a specific choice to use whatever SSL version is
default in the underlying library (<a class="reference external" href="https://github.com/shazow/urllib3">urllib3</a>). Normally this is fine, but from
time to time, you might find yourself needing to connect to a service-endpoint
that uses a version that isn&#8217;t compatible with the default.</p>
<p>You can use Transport Adapters for this by taking most of the existing
implementation of HTTPAdapter, and adding a parameter <em>ssl_version</em> that gets
passed-through to <cite>urllib3</cite>. We&#8217;ll make a TA that instructs the library to use
SSLv3:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">ssl</span>

<span class="kn">from</span> <span class="nn">requests.adapters</span> <span class="kn">import</span> <span class="n">HTTPAdapter</span>
<span class="kn">from</span> <span class="nn">requests.packages.urllib3.poolmanager</span> <span class="kn">import</span> <span class="n">PoolManager</span>


<span class="k">class</span> <span class="nc">Ssl3HttpAdapter</span><span class="p">(</span><span class="n">HTTPAdapter</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;&quot;Transport adapter&quot; that allows us to use SSLv3.&quot;&quot;&quot;</span>

    <span class="k">def</span> <span class="nf">init_poolmanager</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">connections</span><span class="p">,</span> <span class="n">maxsize</span><span class="p">,</span> <span class="n">block</span><span class="o">=</span><span class="bp">False</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">poolmanager</span> <span class="o">=</span> <span class="n">PoolManager</span><span class="p">(</span><span class="n">num_pools</span><span class="o">=</span><span class="n">connections</span><span class="p">,</span>
                                       <span class="n">maxsize</span><span class="o">=</span><span class="n">maxsize</span><span class="p">,</span>
                                       <span class="n">block</span><span class="o">=</span><span class="n">block</span><span class="p">,</span>
                                       <span class="n">ssl_version</span><span class="o">=</span><span class="n">ssl</span><span class="o">.</span><span class="n">PROTOCOL_SSLv3</span><span class="p">)</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="blocking-or-non-blocking">
<h2>Blocking Or Non-Blocking?<a class="headerlink" href="#blocking-or-non-blocking" title="Permalink to this headline">¶</a></h2>
<p>With the default Transport Adapter in place, Requests does not provide any kind
of non-blocking IO. The <a class="reference internal" href="../api.html#requests.Response.content" title="requests.Response.content"><tt class="xref py py-attr docutils literal"><span class="pre">Response.content</span></tt></a>
property will block until the entire response has been downloaded. If
you require more granularity, the streaming features of the library (see
<a class="reference internal" href="#streaming-requests"><em>Streaming Requests</em></a>) allow you to retrieve smaller quantities of the
response at a time. However, these calls will still block.</p>
<p>If you are concerned about the use of blocking IO, there are lots of projects
out there that combine Requests with one of Python&#8217;s asynchronicity frameworks.
Two excellent examples are <a class="reference external" href="https://github.com/kennethreitz/grequests">grequests</a> and <a class="reference external" href="https://github.com/ross/requests-futures">requests-futures</a>.</p>
</div>
<div class="section" id="timeouts">
<h2>Timeouts<a class="headerlink" href="#timeouts" title="Permalink to this headline">¶</a></h2>
<p>Most requests to external servers should have a timeout attached, in case the
server is not responding in a timely manner. Without a timeout, your code may
hang for minutes or more.</p>
<p>The <strong>connect</strong> timeout is the number of seconds Requests will wait for your
client to establish a connection to a remote machine (corresponding to the
<a class="reference external" href="http://linux.die.net/man/2/connect">connect()</a>) call on the socket. It&#8217;s a good practice to set connect timeouts
to slightly larger than a multiple of 3, which is the default <a class="reference external" href="http://www.hjp.at/doc/rfc/rfc2988.txt">TCP packet
retransmission window</a>.</p>
<p>Once your client has connected to the server and sent the HTTP request, the
<strong>read</strong> timeout is the number of seconds the client will wait for the server
to send a response. (Specifically, it&#8217;s the number of seconds that the client
will wait <em>between</em> bytes sent from the server. In 99.9% of cases, this is the
time before the server sends the first byte).</p>
<p>If you specify a single value for the timeout, like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">&#39;https://github.com&#39;</span><span class="p">,</span> <span class="n">timeout</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span>
</pre></div>
</div>
<p>The timeout value will be applied to both the <tt class="docutils literal"><span class="pre">connect</span></tt> and the <tt class="docutils literal"><span class="pre">read</span></tt>
timeouts. Specify a tuple if you would like to set the values separately:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">&#39;https://github.com&#39;</span><span class="p">,</span> <span class="n">timeout</span><span class="o">=</span><span class="p">(</span><span class="mf">3.05</span><span class="p">,</span> <span class="mi">27</span><span class="p">))</span>
</pre></div>
</div>
<p>If the remote server is very slow, you can tell Requests to wait forever for
a response, by passing None as a timeout value and then retrieving a cup of
coffee.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">&#39;https://github.com&#39;</span><span class="p">,</span> <span class="n">timeout</span><span class="o">=</span><span class="bp">None</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="ca-certificates">
<h2>CA Certificates<a class="headerlink" href="#ca-certificates" title="Permalink to this headline">¶</a></h2>
<p>By default Requests bundles a set of root CAs that it trusts, sourced from the
<a class="reference external" href="https://hg.mozilla.org/mozilla-central/raw-file/tip/security/nss/lib/ckfw/builtins/certdata.txt">Mozilla trust store</a>. However, these are only updated once for each Requests
version. This means that if you pin a Requests version your certificates can
become extremely out of date.</p>
<p>From Requests version 2.4.0 onwards, Requests will attempt to use certificates
from <a class="reference external" href="http://certifi.io/">certifi</a> if it is present on the system. This allows for users to update
their trusted certificates without having to change the code that runs on their
system.</p>
<p>For the sake of security we recommend upgrading certifi frequently!</p>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper"><p class="logo">
  <a href="../index.html">
    <img class="logo" src="../_static/requests-sidebar.png" title="Rezzy the Requests Sea Turtle"/>
  </a>
</p>
<p>
<iframe src="http://ghbtns.com/github-btn.html?user=kennethreitz&repo=requests&type=watch&count=true&size=large"
  allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
</p>

<p>
  Requests is an elegant and simple HTTP library for Python, built for
  human beings. You are currently looking at the documentation of the
  development release.
</p>


<h3>Donate</h3>
 <p>
     If you love Requests, consider supporting the author <a href="https://www.gittip.com/kennethreitz/">on Gittip</a>:
 </p>
 <p>
   <iframe style="border: 0; margin: 0; padding: 0;"
       src="https://www.gittip.com/kennethreitz/widget.html"
       width="48pt" height="20pt"></iframe>
 </p>

<h3>Get Updates</h3>
<p>Receive updates on new releases and upcoming projects.</p>

<p><a href="http://tinyletter.com/kennethreitz">Subscribe to Newsletter</a></p>


  <h3><a href="../index.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Advanced Usage</a><ul>
<li><a class="reference internal" href="#session-objects">Session Objects</a></li>
<li><a class="reference internal" href="#request-and-response-objects">Request and Response Objects</a></li>
<li><a class="reference internal" href="#prepared-requests">Prepared Requests</a></li>
<li><a class="reference internal" href="#ssl-cert-verification">SSL Cert Verification</a></li>
<li><a class="reference internal" href="#body-content-workflow">Body Content Workflow</a></li>
<li><a class="reference internal" href="#keep-alive">Keep-Alive</a></li>
<li><a class="reference internal" href="#streaming-uploads">Streaming Uploads</a></li>
<li><a class="reference internal" href="#chunk-encoded-requests">Chunk-Encoded Requests</a></li>
<li><a class="reference internal" href="#post-multiple-multipart-encoded-files">POST Multiple Multipart-Encoded Files</a></li>
<li><a class="reference internal" href="#event-hooks">Event Hooks</a></li>
<li><a class="reference internal" href="#custom-authentication">Custom Authentication</a></li>
<li><a class="reference internal" href="#streaming-requests">Streaming Requests</a></li>
<li><a class="reference internal" href="#proxies">Proxies</a></li>
<li><a class="reference internal" href="#compliance">Compliance</a><ul>
<li><a class="reference internal" href="#encodings">Encodings</a></li>
</ul>
</li>
<li><a class="reference internal" href="#http-verbs">HTTP Verbs</a></li>
<li><a class="reference internal" href="#link-headers">Link Headers</a></li>
<li><a class="reference internal" href="#transport-adapters">Transport Adapters</a><ul>
<li><a class="reference internal" href="#example-specific-ssl-version">Example: Specific SSL Version</a></li>
</ul>
</li>
<li><a class="reference internal" href="#blocking-or-non-blocking">Blocking Or Non-Blocking?</a></li>
<li><a class="reference internal" href="#timeouts">Timeouts</a></li>
<li><a class="reference internal" href="#ca-certificates">CA Certificates</a></li>
</ul>
</li>
</ul>
<h3>Related Topics</h3>
<ul>
  <li><a href="../index.html">Documentation overview</a><ul>
      <li>Previous: <a href="quickstart.html" title="previous chapter">Quickstart</a></li>
      <li>Next: <a href="authentication.html" title="next chapter">Authentication</a></li>
  </ul></li>
</ul>
<div id="searchbox" style="display: none">
  <h3>Quick search</h3>
    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    <p class="searchtip" style="font-size: 90%">
    Enter search terms or a module, class or function name.
    </p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="footer">
      &copy; Copyright 2014. A <a href="http://kennethreitz.com/pages/open-projects.html">Kenneth Reitz</a> Project.
    </div>
    <a href="https://github.com/kennethreitz/requests" class="github">
        <img style="position: absolute; top: 0; right: 0; border: 0;" src="http://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub"  class="github"/>
    </a>
    <script type="text/javascript">
    /* <![CDATA[ */
        (function() {
            var s = document.createElement('script'), t = document.getElementsByTagName('script')[0];
            s.type = 'text/javascript';
            s.async = true;
            s.src = 'http://api.flattr.com/js/0.6/load.js?mode=auto';
            t.parentNode.insertBefore(s, t);
        })();
    /* ]]> */
    </script>
        <script type="text/javascript">
    setTimeout(function(){var a=document.createElement("script");
    var b=document.getElementsByTagName("script")[0];
    a.src=document.location.protocol+"//dnn506yrbagrg.cloudfront.net/pages/scripts/0013/7219.js?"+Math.floor(new Date().getTime()/3600000);
    a.async=true;a.type="text/javascript";b.parentNode.insertBefore(a,b)}, 1);
    </script>

    <script type="text/javascript">
        new HelloBar(36402,48802);
    </script>


    <script type="text/javascript">

      var _gaq = _gaq || [];
      _gaq.push(['_setAccount', 'UA-8742933-11']);
      _gaq.push(['_setDomainName', 'none']);
      _gaq.push(['_setAllowLinker', true]);
      _gaq.push(['_trackPageview']);

      (function() {
        var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
        ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
        var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
      })();

    </script>

    <script type="text/javascript">
      (function() {
        var t   = document.createElement('script');
        t.type  = 'text/javascript';
        t.async = true;
        t.id    = 'gauges-tracker';
        t.setAttribute('data-site-id',
                       '4ddc27f6613f5d186d000007');
        t.src = '//secure.gaug.es/track.js';
        var s = document.getElementsByTagName('script')[0];
        s.parentNode.insertBefore(t, s);
      })();
    </script>
  </body>
</html>